.\" sb(1)
.\"
.\" Copyright (C) 2001, 2003-2006, 2010 The Written Word, Inc.
.\" Copyright (C) 2000-2001 The Written Word, LLC
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2, or (at your option)
.\" any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
.\"
.\" $Id: sb.1 708 2010-02-26 22:19:23Z china $
.\"
.TH sb 1 "2010 February 19"

.SH NAME
sb \- Software program build tool

.SH SYNOPSIS
.ad l
.hy 0
.HP 3
.B sb
.B [\-B|\-\-build]
.B [\-\-builddir=\fR<path>\fB]
.B [\-\-check\-sig]
.B [\-c|\-\-config=\fR<path>\fB]
.B [\-C|\-\-configure]
.B [\-s|\-\-depot=\fR<depot>\fB]
.B [\-G|\-\-dist=\fR<dist>\fB]
.B [\-d|\-\-dist\-ver=\fR<ver>\fB]
.B [\-N|\-\-dry\-run]
.B [\-E|\-\-egd\-socket=\fR<path>\fB]
.B [\-F|\-\-force]
.B [\-\-gpg\-keyring\-path=\fR<path>\fB]
.B [\-h|\-\-help]
.B [\-\-ignoredeps]
.B [\-i|\-\-install]
.B [\-b|\-\-install\-base=\fR<path>\fB]
.B [\-n|\-\-install\-path=\fR<path>\fB]
.B [\-\-local\-depot=\fR<depot>\fB]
.B [\-\-login=\fR<login>\fB]
.B [\-m|\-\-module=\fR<module>\fB]
.B [\-\-password=\fR<pass>\fB]
.B [\-f|\-\-prog\-list=\fR<path>\fB]
.B [\-\-proxy\-host=\fR<host>\fB]
.B [\-\-proxy\-login=\fR<host>\fB]
.B [\-\-proxy\-password=\fR<host>\fB]
.B [\-p|\-\-purge]
.B [\-q|\-\-query=\fR<string>\fB]
.B [\-\-query\-indent=\fR<num>\fB]
.B [\-\-sftp\-known\-hosts\-path=\fR<path>\fB]
.B [\-\-sftp\-private\-key\-path=\fR<path>\fB]
.B [\-t|\-\-test=\fR<test>\fB]
.B [\-U|\-\-uninstall]
.B [\-u|\-\-unpack]
.B [\-\-update\-db]
.B [\-\-validate]
.B [\-v|\-\-verbose]
.B [\-V|\-\-version]
[<program\-name>|<sb\-archive>\ ...]
.ad
.hy

.SH DESCRIPTION
The \fBsb\fR utility unpacks, configures, builds, and installs
software programs. Input is via an XML-based description of the
configure, build, and installation process or an encapsulated archive
containing the XML-based description and relevant source files.

Input is either given as ``<program-name>'' or ``<sb-archive>''. When
given as ``<program-name>'', either the program name or name and
version can be given. When given as ``<sb-archive>'', a
zip-encapsulated archive containing the XML-based description and
relevant sources is expected. The ``<sb-archive>'' path is given as
either a local file or a URL (ftp, http, https, and sftp are
supported).

.SH OPTIONS
.TP 5
.I -B, --build
Execute either the script specified in the ``<build>'' element or the
following script:
.nf
.RS 6
  $ gmake
.RE
.fi

.TP
.I --builddir <path>
Default directory to unpack source files to. Can also be specified in
the configuration file using the ``\fIbuild\-dir\fR'' variable. The
``${SB_BUILD_PREFIX}'' variable is available during configure, build,
and install actions indicating the path of the build directory.

.TP
.I --check-sig
Verify the GPG signature of the program. If \fBsb\fR does not find the
``gpg'' binary in the search path, installation will fail. Before
using this option, the public key used to the sign the package must be
present in your keyring. It is not necessary for the public key to be
signed for signature verification to work. However, it is suggested
that you sign the public key.

.TP
.I -c, --config <path>
Alternate path to configuration file. The default path is
``%sysconfdir%/sbutils.conf''. The format of the configuration file is
documented in
.BR sbutils.conf(4).

.TP
.I -C, --configure
Execute the script specified in the ``<configure>'' element. If not
specified, there is no default.

.TP
.I -s, --depot <depot>
Software depot to search for programs. The path to the depot,
``\fI<depot>\fR'' is either a directory or a URL. The following
methods are supported: ``file://'', ``ftp://'', ``http://'',
``https://'', and ``sftp://''. Multiple software depots can be
specified. The depot specified, \fI<depot>\fR, is the top-level path
to the depot. Through the depot database file, ``depot-db.xml'',
\fBsb\fR will descend into subdirectories of the depot and search in
these directories for additional programs. Any path with the programs
must have the program database file, ``sb\-db.xml'' or
``<program>.sb''. The format of the depot\-db.xml file is documented
in
.BR depot\-db.xml (4).
The format of the sb\-db.xml file is documented in
.BR sb\-db.xml (4).

.TP
.I -G, --dist <dist>
Distribution to build for. The default CD distribution is ``cd''. For
custom builds, ``\fI<dist>\fR'' will be the value assigned.

.TP
.I -d, --dist-ver <ver>
Distribution version to use when specifying a remote depot (http://)
or a local repository that mirrors a remote depot. The distribution
version matches the release number for the packages to install. The
special keyword ``latest'' can be used to specify the most recent
distribution version.

.TP
.I -N, --dry-run
Indicate what actions would be performed but do not execute the
actions. This is useful to determine what commands would be executed
to build the program without having the build occur.

.TP
.I -E, --egd-socket <path>
Pathname to the socket the EGD/PRNGD daemons are listening on. This is
needed only if the remote depot is being accessed through https and
the platform does not have access to a /dev/random device.

.TP
.I -F, --force
Once installed, a program cannot be rebuilt. This option forces a
rebuild of the program. If an updated version of the program is to be
installed in place of the existing older version, this option must be
used to build the new version.

.TP
.I --gpg-keyring-path <path>
Specifies the location of the GPG keyring. The usual location of the
keyring is ~/.gnupg. However, for security reasons, we
encourage use of a dedicated directory for the keyring for
\fBpkg\-inst\fR. This option is required if \fI\-\-check\-sig\fR is
given.

.TP
.I -h, --help
Displays short description of program options and then exits the
program.

.TP
.I --ignoredeps
Used with \-\-uninstall, \-\-update-db, and \-\-purge. Uninstalling a
program is not allowed if another program is dependent on the one
being uninstalled. This option overrides the dependencies and allows
the uninstall of the program. Similarly for \-\-purge. When using
\-\-update-db to update a database entry, the dependencies must be
met. This option overrides the dependency requirement.

.TP
.I -i, --install
Execute either the script specified in the ``<install>'' element or
the following script:
.nf
.RS 6
  $ gmake install
.RE
.fi

.TP
.I -b, --install-base <path>
Installation base directory. Software is expected to be installed in a
directory wholly owned by the software program, ``[install
base]/[install path]''. The installation prefix, combining the
installation base and installation path is available as
``${SB_INSTALL_PREFIX}''.

.TP
.I -n, --install-path <path>
Installation path containing the name of the program. Software is
expected to be installed in a directory wholly owned by the software
program, ``[install base]/[install path]''. The installation path can
contain multiple directory components and the variable
``${SB_INSTALL_NAME}'' which is substituted with the value of the
``<install\-name>'' element. The installation prefix, combining the
installation base and installation path is available as
``${SB_INSTALL_PREFIX}''.

.TP
.I --local-depot <depot>
Specifies the location to a remote repository to hold files retrieved
when the depot is remote. \fBpkg\-inst\fR will create a temporary
working directory to unpack the archives downloaded into the local
depot. The files in the local depot are never removed. As a result,
``\fI<depot>\fR'' can be used later as a depot for \fI\-\-depot\fR.

.TP
.I --login <login>
Login for a remote repository requiring authentication. For the
``ftp://'' method, a default login id of ``anonymous'' is used when no
login id is specified. For the ``http://'' method, HTTP BASIC
authentication is assumed.

.TP
.I -m, --module <module>
Building a program sometimes involves building different parts before
others or building the program in different ways (e.g. a library with
32 and 64-bit libraries). The program description read by \fBsb\fR
defines multiple build methods as modules using the ``<module>''
element. The ``<module>'' element is not required as a default module
is created when the
.BR sb\-db.xml(4)
is parsed using the ``<build\-name>'', ``<install\-name>'',
``<sources>'', ``<dependencies>'', ``<script\-header>'',
``<configure>'', ``<build>'', and ``<install>'' elements. The
\fI\-\-module\fR option indicates which ``\fI<module>\fR'' to use. By
default, the ``\fIdefault\fR'' module is used.

The special module name ``\Iall\fR'' specified all modules. Multiple
uses of ``\fI\-\-module\fR'' are allowed.

.TP
.I --password <pass>
Password for a remote repository requiring authentication. For the
``http://'' method, HTTP BASIC authentication is assumed.

.TP
.I -f, --prog-list <file>
Read \fI<file>\fR for a list of packages. This option can be specified
multiple times.

.TP
.I --proxy-host <host>
If a remote repository is specified, use ``\fI<host>\fR'' as the proxy
server if a proxy is required to connect to remote site.

.TP
.I --proxy-login <login>
Login for a proxy server required to connect with a remote repository.
For the ``ftp://'' method, a connection is initially made to the proxy
host with the proxy login specified by ``\fI<login>\fR''. If a login
to the remote repository is specified, the command ``USER
<login>@<repository>'' is issued to connect to the remote repository
from the proxy server. If a login to the remote repository is not
specified, the command ``USER anonymous@<repository>'' is issued. If a
password to the remote repository is specified, the command `PASS
<password>'' is issued to complete the connection to the remote
repository from the proxy server. If a password to the remote
repository is not specified, the command ``PASS anonymous'' is issued.
For the ``http://'' method, HTTP BASIC authentication is assumed.

.TP
.I --proxy-password <pass>
Password for a proxy server required to connect with a remote
repository. For the ``http://'' method, HTTP BASIC authentication is
assumed.

.TP
.I -p, --purge
Remove the program sources in the build directory.

.TP
.I -q, --query <string>
Request information contained in the program description. The current
supported ``\fB<string>\fR'' values are ``\fBinstall\-prefix\fR'' for
the installation prefix (i.e. the value of ``${SB_INSTALL_PREFIX}''),
``\fBinstall\-name\fR'' for the installation name (i.e. the value of
``${SB_INSTALL_NAME}''), ``\fBmodule\-names\fR'' for a list of all
modules, ``\fBnotes\fR'' for the <notes> element in XML format,
``\fBpatches\fR'' for a list of all patches, ``\fBprogram\-name\fR''
for the value of the ``name'' attribute of the ``<program>'' element,
``\fBprogram\-version\fR'' for the value of the ``version'' attribute
of the ``<program>'' element, ``\fBsbdb-path\fR'' for the path to the
XML-based description file, and ``\fBsources\fR'' for a list of all
source files.

NOTE: ``\fBmodule\-names\fR'' implies ``\fI\-\-module=all\fR''.

.TP
.I --query-indent=\fInum\fR
When \-\-query=changelog or \-\-query=notes is specified, indent the
output by ``\fInum\fR'' characters. Useful as it it not simple to
automatically indent XML output.

.TP
.I --sftp-known-hosts-path <path>
Path to ssh ``ssh_known_hosts'' file. When using the ``sftp://''
protocol for remote repositories, remote hosts are authenticated
against the RSA/DSA host keys in this file.

.TP
.I --sftp-private-key-path <path>
Path to ssh private key file for password-less access to remote
repository. The private key must be created without a password as
\fBpb\fR does not prompt for passwords. The corresponding public key
file must exist in the ``.ssh/authorized_keys'' file on the remote
host for either the user running \fBpb\fR or for the user specified
with ``\fI--login\fR'' option.

.TP
.I -t, --test
Execute the script specified in the ``<test>'' element.

.TP
.I -U, --uninstall
Uninstall program. Execute the script specified in the ``<uninstall>''
element. If no ``<uninstall>'' element exists, the following script is
run:
.nf
.RS 6
  $ rm -rf ${SB_INSTALL_PREFIX}
.RE
.fi

.TP
.I -u, --unpack
Unpack source files specified in the ``<sources>'' element.

.TP
.I --update-db
Update either the build or install database. When used in combination
with \-\-unpack, \-\-configure, \-\-build, \-\-test, \-\-uninstall, or
\-\-purge, operate on the entry in the build database. When used in
combination with \-\-install, operate on the entry in the install
database.

.TP
.I --validate
Ensures all dependencies in the ``<validate>'' element are met.

.TP
.I -v, --verbose
Provide more verbose diagnostics during program execution.

.TP
.I -V, --version
Display version number of \fBsb\fR and exit.

.SH PREPROCESSING
Prior to reading the description file, the XML file is preprocessed by
GPP, the Generic Preprocessor by Denis Auroux
<auroux@math.polytechnique.fr>. This is done to allow one description
file for various configurations.

.SH "BUILD AND INSTALL DATABASE"
sb creates entries in ${SB_BUILD_BASE}/.sb when unpacking,
configuring, building, and testing and in ${SB_INSTALL_BASE}/.sb when
installing a program. When purging a program, the entry for the
specified module is removed. The entries created in the database are
stripped-down versions of the original .sb file containing information
needed by sb to satisfy <depend> entries. Information on the state of
the build is also saved (for the ``state'' element in <depend>
entries).

A new configuration variable was created for the case where a program
being installed installs to the same installation prefix as a program
that already exists in the installation database. By default, a new
entry will be created in the database for the new program. However, if
``rename\-matching\-install\-prefix\-entries'' is set, the old
database entry will be renamed to match the new version of the
program. This makes installation of a program with multiple modules
simple when a few changes are made to one of the modules in a new
version of the program.

Entries in the database should not be edited manually. The
\fI\-\-update\-db\fR option should be used to manage the database
entries if manual editing is necessary.

Appropriate read and write locks are used to prohibit more than one
process from updating an entry in the database at the same time. When
an entry is being updated, a write lock is obtained on the file to
guarantee exclusive access to the file. If another instance of sb is
running, it will obtain read locks on all files and, if encountering a
database entry with an exclusive write lock, will wait at most 10s for
the write lock to complete. Once the 10s time has expired, sb will
fail with an appropriate error message.

.SH REPOSITORY
When \fBsb\fR is not given a
.BR sb\-db.xml(4)
file or ``.sb'' archive file as input, it traverses a list of depots
(repositories) specified with the \fI\-\-depot\fR option. Each
repository path is expected to have either a ``depot\-db.xml'' or
``sb\-db.xml'' file. The ``depot\-db.xml'' file, explained in
.BR depot\-db.xml(4),
allows sb to recursively descend into subdirectories searching for a
program. When depots are used, the leaves usually contain
``sb\-db.xml'' files for each program as follows:
.nf
.RS 2
src/depot-db.xml
src/openssh-3.8.1p1/
src/openssh-3.8.1p1/openssh-3.8.1p1.sb
src/openssh-3.8.1p1/openssh-3.8.1p1.sb-db
src/openssh-3.8.1p1/openssh-3.8.1p1.sb.md5
src/openssh-3.8.1p1/sb-db.xml
src/tetex-2.0.2/
src/tetex-2.0.2/tetex-2.0.2.sb
src/tetex-2.0.2/tetex-2.0.2.sb-db
src/tetex-2.0.2/tetex-2.0.2.sb.md5
src/tetex-2.0.2/sb-db.xml
src/xpm-3.4k/
src/xpm-3.4k/xpm-3.4k.sb
src/xpm-3.4k/xpm-3.4k.sb-db
src/xpm-3.4k/xpm-3.4k.sb.md5
src/xpm-3.4k/sb-db.xml
.RE
.fi

When not specifying a depot, individual ``sb-db.xml'' files or ``.sb'
archive files for each program might be laid out as:
.nf
.RS 2
src/openssh-3.8.1p1.sb
src/tetex-2.0.2.sb
src/xpm-3.4k.sb
.RE
.fi

.SH "ENVIRONMENT VARIABLES"
The following environment variables are set by \fBsb\fR and are
available to the configure, build, and install scripts.

.TP 5
.I SB_BUILD_BASE
Build directory specified with ``\fI--build-dir\fR'' or the
``build-dir'' configuration variable.

.TP
.I SB_BUILD_NAME
Build name specified with the ``<build\-name>'' element.

.TP
.I SB_BUILD_PREFIX
Build prefix, the result of ``${SB_BUILD_BASE}/${SB_BUILD_NAME}''.

.TP
.I SB_INSTALL_BASE
Installation base specified with ``\fI\-\-install\-base\fR'' or the
``install\-base'' configuration variable.

.TP
.I SB_INSTALL_PATH
Installation name specified with ``\fI\-\-install\-path\fR'' or the
``install\-path'' configuration variable.

.TP
.I SB_INSTALL_PREFIX
Installation prefix, the result of
``${SB_INSTALL_BASE}/${SB_INSTALL_PATH}''. This is usually passed as
the value of \-\-prefix in the configure script.

.TP
.I SB_PROG_NAME
Program name as given in the ``name'' attribute of the ``<program>''
element.

.TP
.I SB_PROG_VER
Program version as given in the ``version'' attribute of the
``<program>'' element.

.TP
.I SB_SYSTYPE
System type returned by the GNU config.guess script. The path to the
config.guess script is specified using the ``systype\-path''
configuration variable. The default path is %contribdir%/bin/systype.

.SH "CONFIGURE, BUILD, INSTALL SCRIPTS"
All scripts are run through bash for cross-platform portability. Bash
is invoked with the command-line arguments ``\fI\-\-noprofile\fR'' and
``\fI\-\-norc\fR'' to limit the side-effects of system and
user-settings.

.SH EXAMPLES
Querying the list of modules available for KDE 3.5.10.
.nf
.RS 4
$ sb --query module-names kde-3.5.10
arts
default
kde-i18n-da
kde-i18n-de
kde-i18n-en_GB
kde-i18n-fi
kde-i18n-fr
kde-i18n-uk
kdeadmin
kdeartwork
kdebase
kdegraphics
kdelibs
kdenetwork
kdepim
kdesdk
kdeutils
kdevelop
kdewebdev
.RE
.fi

Using the \fI--dry-run\fR option, build the kdebase module for KDE
3.5.10:
.nf
.RS 4
$ sb --module kdebase --dry-run kde-3.5.10
kde-3.5.10
  searching for depot containing "kdebase" module ... found
    depot: file:///opt/src
  matching system type ... ok
  checking if program exists in local depot ... yes
  reading database entries in /opt/TWWfsw ... done
  syntax checks ...
    checking for build directory ... ok
    checking for build name ... ok
    checking for install name ... ok
  installation prefix ... /opt/TWWfsw/kde35
  build prefix ... /opt/build/kdebase-3.5.10
  unpacking sources ...
    locating dependencies ...
      searching for "pkgconfig" ... /opt/TWWfsw/pkgconfig02
      searching for "fcpackage" ... /opt/TWWfsw/fcpackage26
      searching for "gettext" ... /opt/TWWfsw/gettext017
      searching for "jpeg" ... /opt/TWWfsw/jpeg
      searching for "libiconv" ... /opt/TWWfsw/libiconv112
      searching for "libmng" ... /opt/TWWfsw/libmng10
      searching for "libpng" ... /opt/TWWfsw/libpng12
      searching for "qt" ... /opt/TWWfsw/libqt33
      searching for "qt" (module="gcc42") ... skipping
        note: "x86_64-redhat-linuxe4" does not match system type RE 
        note: "*-aix*|hppa*-hpux*|*-solaris*"
      searching for "tiff" ... /opt/TWWfsw/libtiff38
      searching for "zlib" ... /opt/TWWfsw/libz12
      searching for "/opt/TWWfsw/gcc42r" ... skipping
        note: "x86_64-redhat-linuxe4" does not match system type RE 
        note: "*-aix*|hppa*-hpux*|*-solaris*"
      searching for "gcc" ... skipping
        note: "x86_64-redhat-linuxe4" does not match system type RE 
        note: "*-aix*|hppa*-hpux*|*-solaris*"
      searching for "perl" ... /opt/TWWfsw/perl588
      searching for "coreutils" ... /opt/TWWfsw/coreutils61
      searching for "doxygen" ... /opt/TWWfsw/doxygen15
      searching for "graphviz" ... /opt/TWWfsw/graphviz224
      searching for "tar" ... /opt/TWWfsw/tar12
      searching for "dbus" ... /opt/TWWfsw/dbus12
      searching for "glib" ... /opt/TWWfsw/libglib216
      searching for "glib" (module="gcc42") ... skipping
        note: "x86_64-redhat-linuxe4" does not match system type RE 
        note: "*-aix*|hppa*-hpux*|*-solaris*"
      searching for "bzip2" ... /opt/TWWfsw/bzip210
      searching for "cyrus-sasl" ... /opt/TWWfsw/libsasl21
      searching for "freetype" ... /opt/TWWfsw/libttf23
      searching for "jpeg" ... /opt/TWWfsw/jpeg
      searching for "libart_lgpl" ... /opt/TWWfsw/libart23
      searching for "libxml" ... /opt/TWWfsw/libxml26
      searching for "libxslt" ... /opt/TWWfsw/libxslt11
      searching for "openssl" ... /opt/TWWfsw/libopenssl098
      searching for "pcre" ... /opt/TWWfsw/libpcre78
      searching for "kde" (module="kdelibs") ... /opt/TWWfsw/kde35
      searching for "openldap" ... /opt/TWWfsw/openldap24
      searching for "gawk" ... /opt/TWWfsw/gawk31
    unpacking src/kdebase-3.5.10.tar.bz2
      $ cd /opt/build
      $ /opt/TWWfsw/sbutils13/lib/aux/bzip2/bin/bzip2 -dc 
      /opt/src/latest/graphics/kde-3.5.10/src/kdebase-3.5.10.tar.bz2 | 
      /opt/TWWfsw/sbutils13/lib/aux/gtar/bin/gtar -xvf -
    unpacking quilt patches from src/kdebase-3.5.10/.patches
      $ cd /opt/build/kdebase-3.5.10
      $ /opt/TWWfsw/sbutils13/lib/aux/gpatch/bin/gpatch -p0 -i 
      /opt/src/latest/graphics/kde-3.5.10/src/kdebase-3.5.10/.patches/tww.patch
      $ /opt/TWWfsw/sbutils13/lib/aux/gpatch/bin/gpatch -p0 -i 
      /opt/src/latest/graphics/kde-3.5.10/src/kdebase-3.5.10/.patches/auto.patch
    adding database entry for "kdebase" module ... done
  configuring ...
    locating dependencies ...
      ...
    creating configure script ... /tmp/fileeQlPyj
    executing configure script ...
      $ /opt/TWWfsw/sbutils13/lib/aux/bash/bin/bash --noprofile
      --norc /tmp/fileBUqIKV
    adding database entry for "kdebase" module ... done
  building ...
    locating dependencies ...
      ...
    creating build script ... /tmp/fileeAQsF4
    executing build script ...
      $ /opt/TWWfsw/sbutils13/lib/aux/bash/bin/bash --noprofile
      --norc /tmp/fileL9sI47
    adding database entry for "kdebase" module ... done
.RE
.fi

.SH BUGS
Dependencies are not automatically built.

.SH "SEE ALSO"
.BR depot\-db.xml (4),
.BR sb\-db.xml (4),
.BR sbutils.conf (4)

.SH FILES
.TP 20
.I %sysconfdir%/sbutils.conf
Configuration file

.SH AUTHOR
\fBThe Written Word\fR <info@thewrittenword.com>
